<?xml version="1.0" encoding="utf-8"?>
<!--
                                                                                     
 h       t     t                ::       /     /                     t             / 
 h       t     t                ::      //    //                     t            // 
 h     ttttt ttttt ppppp sssss         //    //  y   y       sssss ttttt         //  
 hhhh    t     t   p   p s            //    //   y   y       s       t          //   
 h  hh   t     t   ppppp sssss       //    //    yyyyy       sssss   t         //    
 h   h   t     t   p         s  ::   /     /         y  ..       s   t    ..   /     
 h   h   t     t   p     sssss  ::   /     /     yyyyy  ..   sssss   t    ..   /     
                                                                                     
	<https://y.st./>
	Copyright © 2016 Alex Yst <mailto:copyright@y.st>

	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 3 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program. If not, see <https://www.gnu.org./licenses/>.
-->
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<base href="https://y.st./en/weblog/2016/01-January/17.xhtml" />
		<title>Too many resource handles; time to work on the spider again &lt;https://y.st./en/weblog/2016/01-January/17.xhtml&gt;</title>
		<link rel="icon" type="image/png" href="/link/CC_BY-SA_4.0/y.st./icon.png" />
		<link rel="stylesheet" type="text/css" href="/link/basic.css" />
		<link rel="stylesheet" type="text/css" href="/link/site-specific.css" />
		<script type="text/javascript" src="/script/javascript.js" />
		<meta name="viewport" content="width=device-width" />
	</head>
	<body>
		<nav>
			<p>
				<a href="/en/">Home</a> |
				<a href="/en/a/about.xhtml">About</a> |
				<a href="/en/a/contact.xhtml">Contact</a> |
				<a href="/a/canary.txt">Canary</a> |
				<a href="/en/URI_research/"><abbr title="Uniform Resource Identifier">URI</abbr> research</a> |
				<a href="/en/opinion/">Opinions</a> |
				<a href="/en/coursework/">Coursework</a> |
				<a href="/en/law/">Law</a> |
				<a href="/en/a/links.xhtml">Links</a> |
				<a href="/en/weblog/2016/01-January/17.xhtml.asc">{this page}.asc</a>
			</p>
			<hr/>
			<p>
				Weblog index:
				<a href="/en/weblog/"><abbr title="American Standard Code for Information Interchange">ASCII</abbr> calendars</a> |
				<a href="/en/weblog/index_ol_ascending.xhtml">Ascending list</a> |
				<a href="/en/weblog/index_ol_descending.xhtml">Descending list</a>
			</p>
			<hr/>
			<p>
				Jump to entry:
				<a href="/en/weblog/2015/03-March/07.xhtml">&lt;&lt;First</a>
				<a rel="prev" href="/en/weblog/2016/01-January/16.xhtml">&lt;Previous</a>
				<a rel="next" href="/en/weblog/2016/01-January/18.xhtml">Next&gt;</a>
				<a href="/en/weblog/latest.xhtml">Latest&gt;&gt;</a>
			</p>
			<hr/>
		</nav>
		<header>
			<h1>Too many resource handles; time to work on the spider again</h1>
			<p>Day 00316: Sunday, 2016 January 17</p>
		</header>
<p>
	Today, I was thinking today about how the <a href="https://secure.php.net/manual/en/ref.gnupg.php">\gnupg_*()</a> functions that I use to sign pages on this site use resource handles, but are not listed on the list of <a href="https://secure.php.net/manual/en/resource.php">resources and the functions that use them</a>.
	I know that several such resource types exist, but what are the chances that I will happen to run across them all? Furthermore, if I do not run across them all, I would only be wrapping the ones that I happen to find out about, which would likely be the ones that are of some use to me personally.
	How arbitrary would that be? With that in mind, I decided to grep the manual.
	The output was enormous.
	While most likely not every file listed is actually a function that I need to wrap, most of those hits are probably actually functions that I need to work with.
	It looks like my little resource-wrapping project is far from over.
	I admittedly did have to tweak my grep input a bit to rule out a bunch of false positives though.
	The first time I used grep, it showed me at least four pages out of every manual section, even if that section did not cover functions that were in need of resource handles.
</p>
<p>
	Among the grep results, I found an <del>idiotically-built</del> <ins>under-documented</ins> class: <a href="https://secure.php.net/manual/en/class.mysqlnduhconnection.php"><code>\MysqlndUhConnection</code></a>.
	<del>It does not seem to actually produce make a database connection and produce the resource handle that it needs upon instantiation.
	Because of this, all of its methods aside from <code>__construct()</code> either require a resource handle as one of their arguments.
	What is even the point in having this be a class to begin with? It is essentially procedural code.
	The manual does not seem to mention what this class is used for, though the example code uses custom subclasses of this class instead of using this class directly.
	The custom subclasses have the same issue as their parent class though.
	While it is possible for a child class to fix the problems by containing a resource as a property, this is not done in the examples.</del> <ins>As it turns out, this class is not meant to instantiate objects that will be used by the programmer directly.
	Instead, they are passed into the <a href="https://secure.php.net/manual/en/function.mysqlnd-uh-set-connection-proxy.php"><code>\mysqlnd_uh_set_connection_proxy()</code> function</a>.
	The reason that the methods take the handles as arguments is that <code>\mysqlnd_uh_set_connection_proxy()</code> causes the object to act on any resource handle passed to certain functions and multiple handles may be used in a script.
	This class is meant to be extended by the programmer to hook into the functions a bit.
	It really had me confused and frustrated when I first read about this class, but now that I understand better, I know that there is nothing wrong with this class.
	There is likewise no need to extend this class and encapsulate a resource, as this class is not built for that type of functionality.
	It would have been nice if the class&apos; main documentation page actually had this information though.
	Instead, no usage information is given there.</ins>
</p>
<p>
	I also ran across an under-documented method that asks for an unspecified type of resource: <a href="https://secure.php.net/manual/en/swfmovie.savetofile.php"><code>\SWFMovie::saveToFile()</code></a>.
	I suspect that the resource handle to use is a file pointer, so I might build this into my f class.
	Next, I found the \bcompiler_*() functions, but I do not like them at all.
	According to the <a href="https://secure.php.net/manual/en/intro.bcompiler.php">introduction</a>, these functions are for use in encoding proprietary <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> applications to avoid having to release the source code for those applications.
	The other use it mentions is to compile <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> code so that the <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> executable for Windows is not needed.
	It looks to me that this extension if for use in environments without package mangers and without source code access.
	Horrified, I decided not to wrap these functions at all.
	I will just ignore them and pretend that they do not exist.
	Another anomaly I ran across rested with the <a href="https://secure.php.net/manual/en/book.mqseries.php">\mqseries_*()</a> functions.
	The functions used to generate resource handles spit three or four of them out at a time, passing those resource handles out by reference.
	It took a few times of reading over this section to figure out where to even get the required resource handles from and I still do not know how the resources are used yet.
	Now that I know where they come from though, I will set those functions aside for now.
</p>
<p>
	After a while, I stopped sorting the grep output.
	There are so many resource types in need of being wrapped in classes and if I continue on this wrapper project, most of include.d will consist of only wrapper classes.
	This is not the vision that I have for my <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> function/class/constant library.
	When I thought there were far less resource types, I accepted the fact that there would be more wrapper classes than other classes for the time being, but I figured that the rest of the library would catch up soon enough.
	Without finishing sorting grep&apos;s output, I already count forty-six wrapper classes that I have not completed in addition to twenty-one wrapper classes that I have already completed and an unknown number of wrapper classes that I have yet to sort out of the grep output.
	There will likely be over eighty wrapper classes to build in total, and that is just too many until I manage to pack more functional code into include.d.
	For now, I will abandon my wrapper class project, aside to add in the wrapper classes that I am actually going to use, such as the one for the gnupg_*() functions.
	I will attempt to push harder on my other projects in an effort to drive my development of include.d code.
	I will push ahead in my development of the onion space spider before working on the Web forum I had planned as well.
	It will be nice to have that in a more presentable state.
	I might still work on wrapper classes when I have nothing at all better to do, or use them to drive my other work forward by telling myself that if I do not get to work on some other project, I will force myself to work on boring wrapper classes instead.
</p>
<p>
	I tried to detach my terminal session from the running spider, but I ended up failing and killing the spider.
	I really hope that the site&apos;s webmaster does not think that my spider&apos;s repeated crawls are an attempt at a <abbr title="distributed denial-of-service">DDoS</abbr> attack.
	This time, I ran it with nohup on the command line.
	This caused the output to not show up on the command line, but perhaps that is for the best.
	The output is being redirected to a file, so I can read it whenever I log back into <a href="/en/domains/cepo.local.xhtml">cepo</a>.
	I also found though that if I delete the logging file, it is not created again with new output.
	Instead, further output seems to be lost.
</p>
<p>
	It seems that I have lost the headphone jack cover for my mobile case.
	I have been unable to locate it for several days.
	Speaking of my mobile, I have shut my Replicant down for the time being.
	My ties to my current carrier are coming to an end, so I have switched the <abbr title="subscriber identity module">SIM</abbr> card over to the wimpy Android that is locked to their service.
	In a few days, after having the device on their service for a while, I will try to get the thing unlocked, then switch back to the Replicant if successful.
</p>
<p>
	We did not end up heading to Eugene and Springfield today, but we are headed out early tomorrow.
</p>
<p>
	My <a href="/a/canary.txt">canary</a> still sings the tune of freedom and transparency.
</p>
		<hr/>
		<p>
			Copyright © 2016 Alex Yst;
			You may modify and/or redistribute this document under the terms of the <a rel="license" href="/license/gpl-3.0-standalone.xhtml"><abbr title="GNU&apos;s Not Unix">GNU</abbr> <abbr title="General Public License version Three or later">GPLv3+</abbr></a>.
			If for some reason you would prefer to modify and/or distribute this document under other free copyleft terms, please ask me via email.
			My address is in the source comments near the top of this document.
			This license also applies to embedded content such as images.
			For more information on that, see <a href="/en/a/licensing.xhtml">licensing</a>.
		</p>
		<p>
			<abbr title="World Wide Web Consortium">W3C</abbr> standards are important.
			This document conforms to the <a href="https://validator.w3.org./nu/?doc=https%3A%2F%2Fy.st.%2Fen%2Fweblog%2F2016%2F01-January%2F17.xhtml"><abbr title="Extensible Hypertext Markup Language">XHTML</abbr> 5.1</a> specification and uses style sheets that conform to the <a href="http://jigsaw.w3.org./css-validator/validator?uri=https%3A%2F%2Fy.st.%2Fen%2Fweblog%2F2016%2F01-January%2F17.xhtml"><abbr title="Cascading Style Sheets">CSS</abbr>3</a> specification.
		</p>
	</body>
</html>

